feat: add Tier selection logic to debug.md and plan-research.md (§7.2 audit fix) by maystudios · Pull Request #194 · maystudios/maxsimcli

maystudios · 2026-03-25T21:59:03Z

Summary

Adds a Tier Selection step to templates/workflows/debug.md (new Step 3) that evaluates CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS and config.execution.parallelism.competition_strategy before spawning debugging agents
Adds a Tier Selection step to templates/workflows/plan-research.md (new Step 6) with the same evaluation logic before spawning researcher agents
Both files now include the Tier 2 Agent Teams path (collaborative debugging / cross-checking researchers) and the Tier 1 graceful degradation path, consistent with the reference implementation in execute.md §6.3

Fixes the §7.2 parallelism audit gap: both workflows were previously hardwired to Tier 1 subagents only, with no awareness of the Agent Teams capability.

Test plan

Verify templates/workflows/debug.md Step 3 references CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS and config.execution.parallelism.competition_strategy
Verify templates/workflows/plan-research.md Step 6 references the same env var and config key
Verify both files include the graceful degradation message and PROJECT.md §7.2 guarantee
Verify step numbering in both files is consistent (no orphaned cross-references)
Verify wording is consistent with the reference implementation in execute.md §6.3

🤖 Generated with Claude Code

…lows Fixes §7.2 audit gap: both workflows were hardwired to Tier 1 only. Each now evaluates CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS and config.execution.parallelism.competition_strategy before spawning agents, using Tier 2 Agent Teams when available and strategy is 'deep', with graceful degradation to Tier 1 otherwise (per PROJECT.md §7.2 guarantee). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

github-actions · 2026-03-25T22:02:56Z

🎉 This PR is included in version 5.15.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

Copilot

Pull request overview

Adds Tier Selection guidance to the workflow templates so debug.md and plan-research.md can account for Agent Teams (Tier 2) vs subagents (Tier 1), addressing the §7.2 parallelism audit gap.

Changes:

Add a new Tier Selection step to templates/workflows/debug.md and renumber subsequent steps.
Add a new Tier Selection step to templates/workflows/plan-research.md, renumber subsequent steps, and update success criteria accordingly.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
templates/workflows/plan-research.md	Adds Tier Selection step before spawning researchers; renumbers steps and updates success criteria checklist.
templates/workflows/debug.md	Adds Tier Selection step before spawning debugging agents; renumbers steps and updates success criteria checklist.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-25T22:03:01Z

templates/workflows/debug.md

+1. **Check Tier 2 availability:**
+   - Verify `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` env var is set (MaxsimCLI installer enables this by default)
+   - Read `config.execution.parallelism.competition_strategy` from `.claude/maxsim/config.json`
+


The Tier 2 availability check here only looks at the env var + config, but the subsequent condition text also references “feature not yet stable”. In execute.md’s reference tier selection, this is handled by doing a lightweight TeamCreate probe before deciding Tier 2 is available. Consider adding the same probe step here (or rewording the condition) so the workflow doesn’t attempt Agent Teams when the feature is enabled but non-functional.

Copilot · 2026-03-25T22:03:02Z

templates/workflows/plan-research.md

+Before spawning researcher agents, evaluate the execution tier:
+
+1. **Check Tier 2 availability:**
+   - Verify `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` env var is set (MaxsimCLI installer enables this by default)
+   - Read `config.execution.parallelism.competition_strategy` from `.claude/maxsim/config.json`
+
+2. **If Tier 2 is available AND `competition_strategy` is `deep`:**
+   - Use Agent Teams cross-checking pattern:
+     - `TeamCreate` to create a research team
+     - Spawn 5-10 researcher teammates, each investigating a different domain independently
+     - Researchers use `SendMessage` to share findings and challenge each other's sources, conclusions, and recommended approaches
+     - Coordinator collects validated findings, flagging areas where agents agree or disagree, and synthesizes a higher-confidence research document
+   - This improves research quality by exposing weak sources and conflicting evidence before the planner acts on findings
+
+3. **If Tier 2 is NOT available (env var unset, feature not yet stable, or `competition_strategy` is `none`/`quick`/`standard`):**
+   - **Graceful degradation to Tier 1** — inform the user:
+     > "Research gathering: using Tier 1 subagents (Agent Teams not available or not required). Each researcher works independently; coordinator collates findings."
+   - Proceed with Tier 1 batch agents as described below (current default path, fully functional)
+
+> **Graceful degradation guarantee:** Per PROJECT.md §7.2, if Agent Teams are unavailable (env var not set, unsupported plan, or feature not yet stable), MaxsimCLI falls back to Tier 1 subagents for all workflows. The user is informed but not blocked.
+


This workflow introduces a Tier 2 (Agent Teams) path for “Research gathering”, but PROJECT.md §7.2’s tier selection table currently specifies “Research gathering → Tier 1 (Subagents)”. Either update this step to match the current spec (Tier 1 only) or adjust the text to explicitly frame Tier 2 research cross-checking as an experimental extension and align the spec/reference docs accordingly.

Suggested change

Before spawning researcher agents, evaluate the execution tier:

1. **Check Tier 2 availability:**

- Verify `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` env var is set (MaxsimCLI installer enables this by default)

- Read `config.execution.parallelism.competition_strategy` from `.claude/maxsim/config.json`

2. **If Tier 2 is available AND `competition_strategy` is `deep`:**

- Use Agent Teams cross-checking pattern:

- `TeamCreate` to create a research team

- Spawn 5-10 researcher teammates, each investigating a different domain independently

- Researchers use `SendMessage` to share findings and challenge each other's sources, conclusions, and recommended approaches

- Coordinator collects validated findings, flagging areas where agents agree or disagree, and synthesizes a higher-confidence research document

- This improves research quality by exposing weak sources and conflicting evidence before the planner acts on findings

3. **If Tier 2 is NOT available (env var unset, feature not yet stable, or `competition_strategy` is `none`/`quick`/`standard`):**

- **Graceful degradation to Tier 1** — inform the user:

> "Research gathering: using Tier 1 subagents (Agent Teams not available or not required). Each researcher works independently; coordinator collates findings."

- Proceed with Tier 1 batch agents as described below (current default path, fully functional)

> **Graceful degradation guarantee:** Per PROJECT.md §7.2, if Agent Teams are unavailable (env var not set, unsupported plan, or feature not yet stable), MaxsimCLI falls back to Tier 1 subagents for all workflows. The user is informed but not blocked.

Before spawning researcher agents, confirm the execution tier for this workflow:

1. **Lock research gathering to Tier 1 (Subagents):**

- Per PROJECT.md §7.2, the "Research gathering" phase MUST use Tier 1 subagents only.

- Do **not** use Agent Teams (Tier 2) for this workflow, even if `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` is set or `competition_strategy` is `deep`.

2. **User-facing confirmation:**

- Inform the user explicitly that research is running in Tier 1 mode:

> "Research gathering: using Tier 1 subagents as required by PROJECT.md §7.2. Each researcher works independently; the coordinator collates and synthesizes findings."

- Then proceed with Tier 1 batch agents as described below (this is the required and fully supported path).

> **Graceful degradation guarantee (project-wide):** Per PROJECT.md §7.2, if Agent Teams are unavailable (env var not set, unsupported plan, or feature not yet stable), MaxsimCLI falls back to Tier 1 subagents for all workflows. This specific research sub-workflow is **always** Tier 1 by design, so it does not depend on Agent Teams availability.

Copilot · 2026-03-25T22:03:02Z

templates/workflows/plan-research.md

+1. **Check Tier 2 availability:**
+   - Verify `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` env var is set (MaxsimCLI installer enables this by default)
+   - Read `config.execution.parallelism.competition_strategy` from `.claude/maxsim/config.json`
+


The Tier 2 availability check here only covers the env var + config, but the later condition text also includes “feature not yet stable”. execute.md’s tier selection covers this by doing a lightweight TeamCreate probe before opting into Tier 2. Consider adding the same probe step here (or rewording the condition) to avoid attempting Agent Teams when enabled but non-functional.

Copilot · 2026-03-25T22:03:02Z

templates/workflows/debug.md

+2. **If Tier 2 is available AND `competition_strategy` is `deep`:**
+   - Use Agent Teams collaborative debugging pattern:
+     - `TeamCreate` to create a debug team


PROJECT.md §7.2’s tier selection table lists “Collaborative debugging → Tier 2 (Agent Teams)”, but this workflow only opts into Tier 2 when competition_strategy is deep. If competition_strategy is meant to gate Tier 2 usage outside competitive implementation, the spec/reference docs should be updated to reflect that; otherwise consider removing this gating for debugging.

Copilot AI review requested due to automatic review settings March 25, 2026 21:59

Copilot started reviewing on behalf of maystudios March 25, 2026 21:59 View session

maystudios merged commit 5674fae into main Mar 25, 2026
3 checks passed

github-actions bot added the released label Mar 25, 2026

Copilot AI reviewed Mar 25, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add Tier selection logic to debug.md and plan-research.md (§7.2 audit fix)#194

feat: add Tier selection logic to debug.md and plan-research.md (§7.2 audit fix)#194
maystudios merged 1 commit intomainfrom
worktree-agent-a0f88490

maystudios commented Mar 25, 2026

Uh oh!

Uh oh!

github-actions bot commented Mar 25, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 25, 2026

Uh oh!

Copilot AI Mar 25, 2026

Uh oh!

Copilot AI Mar 25, 2026

Uh oh!

Copilot AI Mar 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

maystudios commented Mar 25, 2026

Summary

Test plan

Uh oh!

Uh oh!

github-actions bot commented Mar 25, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants